/******************************************************************************
 Copyright (c) 2024-2025 Qualcomm Technologies International, Ltd.
 All Rights Reserved.
 Qualcomm Technologies International, Ltd. Confidential and Proprietary.

******************************************************************************/
/*!
@file    gatt_ras_server.h
@brief   Header file for the Ranging Service library.

        This file provides documentation for the GATT Ranging Server library
        API (library name: Gatt_ras_server).
*/

#ifndef GATT_RAS_SERVER_H
#define GATT_RAS_SERVER_H

#include "csr_bt_config.h"

#ifdef INSTALL_CHANNEL_SOUNDING_SUPPORT

#include "csr_bt_gatt_lib.h"
#include "csr_bt_gatt_prim.h"
#include "service_handle.h"
#include "csr_bt_tasks.h"


typedef ServiceHandle RasServiceHandleType;
typedef connection_id_t ConnectionIdType;

/*! @brief Client Config data.

    This structure contains the client configuration of all the characteristics
    of the Ranging Service
 */

typedef struct
{
    uint16    realTimeDataClientCfg;
    uint16    onDemandDataClientCfg;
    uint16    controlPointClientCfg;
    uint16    dataReadyClientCfg;
    uint16    dataOverwrittenClientCfg;
} GattRasServerConfigType;

/*! @brief The set of messages an application task can receive from the RAS library.
 */
typedef uint16 GattRasServerMessageId;

#define GATT_RAS_SERVER_CONFIG_CHANGE_IND           ((GattRasServerMessageId)0)
#define GATT_RAS_SERVER_RANGING_ENABLE_IND          ((GattRasServerMessageId)1)
#define GATT_RAS_SERVER_RANGING_DATA_OPERATION_IND  ((GattRasServerMessageId)2)

typedef uint8 GattRasServerOperation;

#define GATT_RAS_SERVER_OP_RANGING_DATA_READY       ((GattRasServerOperation)0)
#define GATT_RAS_SERVER_OP_GET_RANGING_DATA         ((GattRasServerOperation)1)
#define GATT_RAS_SERVER_OP_COMPLETE_RANGING_DATA    ((GattRasServerOperation)2)
#define GATT_RAS_SERVER_OP_ACK_RANGING_DATA         ((GattRasServerOperation)3)
#define GATT_RAS_SERVER_OP_COMPLETE_LOST_RANGING_DATA   ((GattRasServerOperation)4)
#define GATT_RAS_SERVER_OP_ABORT_OPERATION          ((GattRasServerOperation)5)
#define GATT_RAS_SERVER_RANGING_DATA_OVERWRITTEN    ((GattRasServerOperation)6)

/*! @brief Contents of the GATT_RAS_SERVER_CONFIG_CHANGE_IND message that is sent by the library,
    when any CCCD char is toggled by the client.
 */
typedef struct 
{
    GattRasServerMessageId id;
    ServiceHandle rasServiceHandle;
    ConnectionIdType cid;
    bool configChangeComplete; /* will be TRUE if all CCCD of RAS are written once */
} GattRasServerConfigChangeInd;

/*! @brief Contents of the GATT_RAS_SERVER_RANGING_ENABLE_IND message that is sent by the library,
    when CS Ranging enable/disable is received by controller.
 */
typedef struct 
{
    GattRasServerMessageId id;
    ServiceHandle rasServiceHandle;
    ConnectionIdType cid;
    uint8 csRangingEnable;
} GattRasServerRangingEnableInd;

/*! @brief Contents of the GATT_RAS_SERVER_RANGING_DATA_OPERATION_IND message that is sent by the library,
    when remote client writes RAS-Control Point operations
    startSegment and endSegment shall be valid only if operation is GATT_RAS_SERVER_OP_COMPLETE_LOST_RANGING_DATA
    For all other opertations library will send these parameters as 0.
 */
typedef struct 
{
    GattRasServerMessageId id;
    ServiceHandle rasServiceHandle;
    ConnectionIdType cid;
    GattRasServerOperation operation;
    uint16 rangingCounter;
    uint8 startSegment;
    uint8 endSegment;
} GattRasServerRangingDataOperationInd;


/*!
    @brief Instantiate the GATT Ranging Service Library.

    The GATT Ras Service Init function is responsible for allocating its instance
    memory and returning a unique service handle for that instance. The Service handle
    is then used for the rest of the API.

    @param appTask The Task that will receive the messages sent from this Ranging service library.
    @param startHandle This indicates the start handle of the RAS service
    @param endHandle This indicates the end handle of the RAS service
    @param rasFeatures RAS features supported

    @return RasServiceHandleType If the service handle returned is 0, this indicates a failure
    during GATT Service initialisation.

*/
RasServiceHandleType GattRasServerInit(AppTask appTask, uint16 startHandle, uint16 endHandle, uint32 rasFeatures);

/*!
    @brief Remove the configuration for a peer device, identified by its
           Connection ID.

    This removes the configuration for that peer device from the
    service library, freeing the resources used for that config.
    This should only be done when the peer device is disconnecting.

    @param handle The server instance handle returned in GattRasServerInit().
    @param cid  The cid with the remote device.

    @return GattRasServerConfigType  Pointer to the peer device configuration
            data. It is the applications responsibility to cache/store
            this between connections of paired peer devices, and for
            freeing the allocated memory.

*/
GattRasServerConfigType *GattRasServerRemoveConfig(
                          RasServiceHandleType handle,
                          ConnectionIdType cid);


/*!
    @brief Add configuration for a paired peer device, identified by its
           Connection ID (CID).

    @param handle The server instance returned in GattRasServerInit().
    @param cid The Connection ID to the peer device.
    @param config  Client characteristic configurations for this connection.
           If this is NULL, this indicates a default config should be used for the
           peer device identified by the CID.

    @return status_t status of the Add Configuration operation.

*/
status_t GattRasServerAddConfig(
                          RasServiceHandleType handle,
                          ConnectionIdType cid,
                          GattRasServerConfigType *config);

/*!
    @brief This API is used for informing Maximum Remote Receiver MTU
           which shall be used for segment creation

    @param handle The server instance returned in GattRasServerInit().
    @param cid The Connection ID to the peer device.
    @param remoteRxMtu Remote Rx MTU value that remote device can receive

    @return TRUE if MTU values are accepted else FAIL.

    NOTE: If this API is not called, then default MTU of
          23 octets shall be used for segment generation.

*/
bool GattRasServerSetRangingDataMtu(
                          RasServiceHandleType handle,
                          ConnectionIdType cid,
                          uint16 remoteRxMtu);

/*!
    @brief This API is used to inform remote client that Ranging Data is ready to
           be transmitted to the client. This API needs to be called when 
           higher layer receives GATT_RAS_SERVER_RANGING_DATA_OPERATION_IND prim
           with GattRasServerOperation = GATT_RAS_SERVER_OP_RANGING_DATA_READY

    @param handle The server instance returned in GattRasServerInit().
    @param cid The Connection ID to the peer device.
    @param rangingCounter Ranging Counter for CS Procedure ready

    @return TRUE if Ranging Data Ready is sent else FAIL.

*/
bool GattRasServerRangingDataReady(RasServiceHandleType handle, ConnectionIdType cid, uint16 rangingCounter);


/*!
    @brief This API is used to inform remote client that complete Ranging Data
           is sent to the client. This API needs to be called when 
           higher layer receives GATT_RAS_SERVER_RANGING_DATA_OPERATION_IND prim
           with GattRasServerOperation = GATT_RAS_SERVER_OP_COMPLETE_RANGING_DATA

    @param handle The server instance returned in GattRasServerInit().
    @param cid The Connection ID to the peer device.
    @param rangingCounter Ranging Counter for CS Procedure ready

    @return TRUE if Complete Ranging Data is sent else FAIL.

*/
bool GattRasServerCompleteRangingDataResponse(RasServiceHandleType handle,
    ConnectionIdType cid,
    uint16 rangingCounter);


/*!
    @brief This API is used to inform remote client that Complete Lost Ranging
           Data Segment is sent to the client. This API needs to be called when 
           higher layer receives GATT_RAS_SERVER_RANGING_DATA_OPERATION_IND prim
           with GattRasServerOperation = GATT_RAS_SERVER_OP_COMPLETE_LOST_RANGING_DATA

    @param handle The server instance returned in GattRasServerInit().
    @param cid The Connection ID to the peer device.
    @param rangingCounter Ranging Counter for CS Procedure ready
    @param startSegment Start segment that from which data need to be retransmit
    @param endSegment End segment that to which data need to be retransmit

    @return TRUE if Complete Ranging Data is sent else FAIL.

*/
bool GattRasServerCompleteLostRangingDataSegmentResponse(RasServiceHandleType handle,
    ConnectionIdType cid,
    uint16 rangingCounter,
    uint8 startSegment,
    uint8 endSegment);

/*!
    @brief This API is used to inform remote client that Ranging
           Data for rangingCounter is flushed or overwritten.
           This API needs to be called when higher layer receives 
           GATT_RAS_SERVER_RANGING_DATA_OPERATION_IND prim
           with GattRasServerOperation = GATT_RAS_SERVER_RANGING_DATA_OVERWRITTEN

    @param handle The server instance returned in GattRasServerInit().
    @param cid The Connection ID to the peer device.
    @param rangingCounter Ranging Counter for CS Procedure ready

    @return TRUE if Complete Ranging Data is sent else FAIL.

*/
bool GattRasServerRangingDataOverwritten(RasServiceHandleType handle,
    ConnectionIdType cid,
    uint16 rangingCounter);

/*!
    @brief This API is used by Application to flush Ranging Data maintained for
    the connection cid.

    @param handle The server instance returned in GattRasServerInit().
    @param cid The Connection ID to the peer device.
    @param rangingCounter Ranging Counter for CS Procedure ready

    @return TRUE if Ranging Data is flushed else FAIL.

*/
bool GattRasServerFlushRangingData(RasServiceHandleType handle, ConnectionIdType cid, uint16 rangingCounter);

#endif /* INSTALL_CHANNEL_SOUNDING_SUPPORT */

#endif /* GATT_RAS_SERVER_H */